-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
Document named arguments BC policy #14566
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
We should attach that footnote to |
For reference: It's maybe good to include "unless specified otherwise". For instance, it might make sense to support named arguments in attributes or specific data objects (I'm thinking about some of the newer "configuration" data objects in the RateLimiter and Mailer components). However, before I want to document that, I think we should have a standardized (in Symfony) way of indicating this in the PHPdoc or the like (documentation?). |
I agree. A PHP8 attribute would be nice. The only issue is where to put it. Maybe we don't need a package for that? After all, that's not mandatory: attributes can be added/read without any implementation. We'd just need to settle on its name (and we could provide an optional package of course). |
We could build a new contracts package for attributes like that, e.g. |
I'm not exactly sure what this package should do. Do we want to trigger notices when using an uncovered named argument, like we do when extending a class that's |
Static code analyzers (phpstan, psalm, PhpStorm) could pick this up and issue a warning. I don't think that we can trigger notices in such a case, can we? |
I think it would be better to not jump the line and introduce attributes for documentation purposes, before there is a common direction that the tools are moving into. At the moment I can't find anything about attribute support for PhpDocumentor and PHPstan. Psalm seems to lean against attributes for static analysis (but has support for people wanting to use it like that), while PHPstorm added attributes for static analysis. I think - if we can't do any analysis on it ourselves - the best option is to just add it to the PHPdoc description and e.g. include a small "tip" or "note" in documentation when named arguments are covered (e.g. when introducing the |
I definitely think that attributes should be used by static analyzers/IDEs yes. |
Named arguments is a major feature of PHP8, and is very pleasant to use. Shouldn't we progressively move from promoting ordered argument to promote named arguments? We could use the proposed annotation to indicate if the class supports the old (ordered) or the new (named) BC promise. Supporting both doesn't worth it in my opinion (too much work). |
Thank you Wouter. |
No description provided.